home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 July / Macworld (1999-07).dmg / MPEG 3 Utilities / MacAMP 1.0b7 / Visual Plugins Programming / visual.h < prev   
C/C++ Source or Header  |  1999-01-30  |  6KB  |  141 lines
  1. #pragma once
  2.  
  3. /*
  4.     Visual Plug-in API
  5.     ©1998, @soft
  6.     
  7.     Description:    The plugin API for MacAmp visual plugins.
  8.     Version:        1.2
  9.     Released:        1/30/99
  10.     Compatibility:    MacAmp 1.0b7+
  11.     Version history:
  12.     
  13.      Date    Who        Changes
  14.     ------+------+------------------------------------------------------
  15.     013099    SK        Added extended stuff for 1.1 plugins.
  16.     090598    SK        Commented the file, cleaned the unnesessary stuff.
  17.     090198  SK        Initial release
  18. */
  19.  
  20. #define VP_API_VERSION        0x01
  21. #define VP_EXT_API_VERSION    0x02
  22.  
  23. // Plugin types
  24. enum {
  25.     plugVisual        = 'vis!'    // Visual plugin
  26. };
  27.  
  28. // Plugin return values
  29. enum {
  30.     visNoErr        = noErr,
  31.     visTerminate    = 1,        // terminate the plugin
  32.     visNoMemory        = 2,        // terminate the plugin and display no memory alert
  33.         // all other returns will cause plugin termination and "unknown plugin error" alert.
  34.     
  35.     callbackNoSong    = 1310,        // Returned by callback (see below), if you're trying to get information
  36.                                 // about the song while none is playing.
  37.     callbackNoID3    = 1311        // Returned by callback (see below) callback->getID3, if no ID3 tag information
  38.                                 // for the song is present. Note that id3short is still valid and contains
  39.                                 // file name.
  40. };
  41.  
  42. // plugin flags
  43. enum {
  44.     flagHasSettings        = 0x01,        // Plugin can display and handle settings dialog
  45.     flagGetKeyDown        = 0x02,        // Plugin wants to get keydown events
  46.     flagGetIdle            = 0x04        // Plugin wants to get idle events
  47. };
  48.  
  49. // Function prototypes (see dummy plug for the explanations)
  50. extern OSErr    PlugInitialize(WindowPtr* window, FSSpecPtr plug, UInt32* refcon);
  51. extern OSErr    PlugTerminate(WindowPtr window, UInt32* refcon);
  52. extern OSErr    PlugProcess(WindowPtr window, short chan, const double* stream, short dataSize, UInt32* refcon);
  53. extern OSErr    PlugMacEvent(WindowPtr window, EventRecord* event, UInt32* refcon);
  54. extern OSErr    PlugKeyDown(WindowPtr window, char key, short modifiers, UInt32* refcon);
  55. extern OSErr    PlugIdle(WindowPtr window, UInt32* refcon);
  56. extern OSErr    PlugSettings(WindowPtr window, UInt32* refcon);
  57. extern OSErr    PlugAbout(WindowPtr window, UInt32* refcon);
  58. // • NEW FOR 1.2 •
  59. // Gets called immediately before the song start. You can obtain ID3 information about the track here etc
  60. // if you want -- it won't be changed until next song starts.
  61. extern OSErr    PlugSongStart(WindowPtr window, UInt32* refcon);
  62. // Gets called immediately after the song end. It is a good idea to clear/stop any animations at this point
  63. // because you will not receive PlugProcess calls until next song is started -- that can happen in one
  64. // minute/one second or never. You never know. =)
  65. extern OSErr    PlugSongEnd(WindowPtr window, UInt32* refcon);
  66.  
  67. // Type defeinitions for plugin callbacks.
  68. typedef OSErr    (*vpPlugInitializeProcPtr)(WindowPtr* window, FSSpecPtr plug, UInt32* refcon);
  69. typedef OSErr    (*vpPlugTerminateProcPtr)(WindowPtr window, UInt32* refcon);
  70. typedef OSErr    (*vpPlugProcessProcPtr)(WindowPtr window, short chan, const double* stream, short dataSize, UInt32* refcon);
  71. typedef OSErr    (*vpPlugMacEventProcPtr)(WindowPtr window, EventRecord* event, UInt32* refcon);
  72. typedef OSErr    (*vpPlugKeyDownProcPtr)(WindowPtr window, char key, short modifiers, UInt32* refcon);
  73. typedef OSErr    (*vpPlugIdleProcPtr)(WindowPtr window, UInt32* refcon);
  74. typedef OSErr    (*vpPlugSettingsProcPtr)(WindowPtr window, UInt32* refcon);
  75. typedef OSErr    (*vpPlugAboutProcPtr)(WindowPtr window, UInt32* refcon);
  76. typedef OSErr    (*vpPlugSongStartProcPtr)(WindowPtr window, UInt32* refcon);
  77. typedef OSErr    (*vpPlugSongEndProcPtr)(WindowPtr window, UInt32* refcon);
  78.  
  79. // • NEW FOR 1.2 •
  80. // These are typedefs for MacAMP hook routines. If you're specified VP_EXT_API_VERSION in gPlugInfo.api,
  81. // these will be filled for you by MacAMP so you can call them to obtain information about the current
  82. // song.
  83.  
  84. // This callback fills the FSSpec* to the currently playing song or returns callbackNoSong if no song
  85. // is currently playing.
  86. typedef OSErr    (*maGetCurrentFSSpecProcPtr)(FSSpec* spec);
  87. // Fills current track time (either real or reverse, depending on the bool setting reverse)
  88. // Time is in seconds. You can get it by sec = (*time)%60; min = (*time)/60;
  89. // Returns callbackNoSong if no song is playing.
  90. typedef OSErr    (*maGetCurrentTimeProcPtr)(Boolean reverse, UInt32* time);
  91. // Fills current track position. Short will contain the position in percents, in range of 0-100.
  92. // Returns callbackNoSong if no song is playing.
  93. typedef OSErr    (*maGetCurrentPosProcPtr)(UInt16* position);
  94. // Fills current track ID3 information. If no ID3 tags found, only id3short is filled and
  95. // callbackNoID3 error is returned.
  96. // id3short is a string containing ID3 tags formatted in form
  97. //  Artist - Title
  98. // id3long is a char* containing fully formatted ID3 tags in form
  99. //  Artist - Title - Album - Year
  100. // Make sure id3long is at least 1024 bytes long to avoid buffer overflow, as MA does not checks
  101. // for the length.
  102. // Returns callbackNoSong if no song is playing.
  103. typedef OSErr    (*maGetID3InformationProcPtr)(StringPtr id3short, char* id3long);
  104. // Returns the Ptr to qd globals.
  105. typedef QDGlobalsPtr (*maGetQDPtrProcPtr)(void);
  106.  
  107. typedef struct {
  108.     maGetCurrentFSSpecProcPtr    getFSSpecProc;
  109.     maGetCurrentTimeProcPtr        getCurrentTimeProc;
  110.     maGetCurrentPosProcPtr        getCurrentPosProc;
  111.     maGetID3InformationProcPtr    getID3Proc;
  112.     maGetQDPtrProcPtr            getQDPtrProc;
  113. } MAVisCallbacks, *MAVisCallbacksPtr;
  114.  
  115. typedef struct {
  116.     UInt16    api;                                // API used. Should contain VP_EXT_API_VERSION.
  117.     OSType    type;                                // Plugin type. Should always be plugVisual.
  118.     
  119.     UInt32    flags;                                // Plugin flags (flagXXX constants)
  120.     UInt32    globRefcon;                            // Any global refcon you wish to use.
  121.     
  122.     Str63    name;                                // Plugin name (displayed in Plugin menu)
  123.     
  124.         // Pointers to plugin functions, or nil if they are not implemented.
  125.     vpPlugInitializeProcPtr        initProc;
  126.     vpPlugTerminateProcPtr        terminateProc;
  127.     vpPlugProcessProcPtr        processProc;
  128.     vpPlugMacEventProcPtr        macEventProc;
  129.     vpPlugKeyDownProcPtr        keyDownProc;
  130.     vpPlugIdleProcPtr            idleProc;
  131.     vpPlugSettingsProcPtr        settingsProc;
  132.     vpPlugAboutProcPtr            aboutProc;
  133.     
  134.     // • NEW FOR 1.2 •
  135.     vpPlugSongStartProcPtr        songStartProc;
  136.     vpPlugSongEndProcPtr        songEndProc;
  137.     
  138.     MAVisCallbacksPtr            callbacks;
  139. } VPInfoBlock, *VPInfoPtr;
  140.  
  141.